packages/stac/lib/src/parsers/widgets/stac_badge/stac_badge_parser.dart (1)

21-23: Consider validation instead of assertions for production safety.

The assertions validate count and maxCount, but assertions are disabled in production/release builds. While this matches Flutter's Badge widget pattern, invalid values could pass through silently in production.

Consider adding explicit validation:

-    assert(model.count! >= 0, 'count must be non-negative');
+    if (model.count! < 0) {
+      throw ArgumentError('count must be non-negative');
+    }
     final maxCount = model.maxCount ?? 999;
-    assert(maxCount > 0, 'maxCount must be positive');
+    if (maxCount <= 0) {
+      throw ArgumentError('maxCount must be positive');
+    }

packages/stac_core/lib/widgets/badge/stac_badge.dart (2)

127-147: Enforce or centralize count >= 0 and maxCount > 0 constraints.

The docs state that count must be non‑negative and maxCount must be positive, but the model itself doesn’t enforce this. If validation currently lives only in StacBadgeParser, consider either:

• Adding simple assertions in the constructor, or
• Clearly documenting in this file that validation is performed at the parser layer.

This keeps behavior predictable if other consumers instantiate StacBadge directly.

---

81-95: Align JSON deserialization defaults for maxCount/isLabelVisible with documented values.

You document maxCount as defaulting to 999 and isLabelVisible as effectively default‑true, and you set those as constructor defaults. Depending on your json_serializable configuration, objects built via fromJson may still see these as null when the keys are absent, pushing defaulting logic into the parser.

To keep defaults declarative at the model level and reduce duplication in parsers, consider adding explicit @JsonKey(defaultValue: ...) annotations, e.g.:

@@
-  /// Maximum count value before showing '[maxCount]+' format.
-  ///
-  /// Only used when [count] is provided. Defaults to 999.
-  /// Must be positive (> 0).
-  final int? maxCount;
+  /// Maximum count value before showing '[maxCount]+' format.
+  ///
+  /// Only used when [count] is provided. Defaults to 999.
+  /// Must be positive (> 0).
+  @JsonKey(defaultValue: 999)
+  final int? maxCount;
@@
-  /// If false, the badge's [label] is not included.
-  final bool? isLabelVisible;
+  /// If false, the badge's [label] is not included.
+  @JsonKey(defaultValue: true)
+  final bool? isLabelVisible;

This keeps model semantics consistent whether instances are created directly or via JSON.

Also applies to: 140-147

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

docs/widgets/badge.mdx (2)

21-23: Clarify label vs count interaction and count constraints in docs

The properties table doesn’t currently call out that when count is provided, label is ignored, and that count must be non‑negative and maxCount positive (as enforced/assumed in the Dart model and Flutter’s Badge.count). Consider expanding the label, count, and maxCount rows to spell this out so JSON authors don’t end up with surprising behavior or invalid values.

---

136-143: Verify alignment JSON shape matches StacAlignmentGeometry expectations

The custom styling example uses:

"alignment": {
  "dx": 1.0,
  "dy": -1.0
}

Please double‑check this matches how StacAlignmentGeometry is documented elsewhere (some APIs use x/y instead of dx/dy). If the canonical shape differs, updating this example will prevent confusion for users copying it.

packages/stac_core/lib/widgets/badge/stac_badge.dart (1)

78-81: Consider centralizing count/maxCount validation beyond the .count factory

Right now, invariants for count and maxCount (non‑negative count, positive maxCount) are only enforced via asserts in StacBadge.count. Instances created via the main constructor or fromJson can carry invalid values through to the Flutter Badge, which will then assert at build time.

To make behavior more predictable for server‑driven JSON:

• Either move the count >= 0 / maxCount > 0 checks into the primary constructor (or a shared private initializer) so all code paths enforce them, or
• Add explicit validation in the parser / JSON layer and document how invalid values are handled (e.g., clamped or falling back to defaults).

This isn’t a blocker, but tightening this up would give earlier and clearer feedback when JSON is misconfigured.

Also applies to: 97-105, 121-151, 183-200

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro